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TRSDOS 16 OWNER'S MANUAL 


TRS-80 


TECHNICAL INFORMATION 


MEMORY REQUIREMENTS 


TRSDOS-16 loads into memory at startup and occupies 
approximately 48K of memory. 

At this time TRSDOS-16 also processes your configuration 
command file (see APPENDIX B for information on the 
Configuration Command File). 

The configuration file tells TRSDOS-16 what files to load 
into memory for your use. This might include RUNCOBOL, and 
the Debugger. TRSDOS-16 loads these files into the memory 
area reserved for TRSDOS-16. 

Any memory following the configured files is available to 
you, the user. 

Note: The Editor, Assembler, and Linker load into user 

memory, not the Configurator memory. 


RELATIVE ADDRESSING 

TRSDOS-16 loads into memory in a way that is "invisible" to 
the user. This is TRSDOS-16's way of protecting itself 
from being modified by other programs. 

TRSDOS-16 internally keeps track of two addresses: 

. the BASE address - this is the bottom of user 

memory. (Memory below this address is reserved for 
TRSDOS-16 and files designated by the configured 
file. 

. the BOUNDS address - this is the top address of 
memory. (H'lFFFF in a 128K Model 16, H'3FFFF in a 
256K Model 16, H'5FFFF in a 384K Model 16, and 
H'7FFFF in a 512K Model 16.) 

In short: 

BOUNDS Address - BASE Address = User Memory 
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TRSDOS-16 uses the BASE Address to find the physical loading 
address of your program. When you write a machine-language 
program, you assign it a "relative loading" address, usually 
zero. TRSDOS-16 then adds the BASE address to this relative 
address to determine the physical address where it will load 
your program: 

BASE Address + PROGRAM RELATIVE ADDRESS = PHYSICAL 

LOAD ADDRESS 


TRSDOS—16 uses the BOUNDS address to find the amount of 
available user memory. This is how the Operating System 
determines if your program will fall out of the "bounds" of 
user memory. 
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BEGINNING OF 
MEMORY 


TRS-80 


> 


TRSDOS-16 


DEBUG 
IF LOADED 


RUNCOBOL 
IF LOADED 

BASE ADDRESS —> - 


USER 

MEMORY 


BOUNDS ADDR —> - 

| RESERVED 

TOP OF PHYSICAL —> - 

MEMORY (16K) 


MEMORY CHART 
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DISK ORGANIZATION 


FLOPPY DISKETTE 

TRSDOS-16 can use either single-sided (double density) or 
double-sided (double density) diskettes. However, if you 
are using an Enhanced Model II, you can use only 
single-sided diskettes because of the type of drives you 
have. 

TRSDOS-16 will automatically format either single or 
double-sided diskettes according to the type of diskette. 

Each side of the double-sided diskette contains 77 tracks, 
numbered J0 - 76. Therefore, the double-sided diskette can 
be thought of as one diskette with 154 tracks. 

The single-sided diskette has 77 tracks on one side only. 

Each track is made up of 32 sectors, numbered 1-32. Each 
sector contains 256 bytes, except for track 0 (one side only 
on the double-sided diskette). This track 0 is reserved for 
System use and is formatted single-density. It contains 26 
sectors and 128 bytes per sector. 

The total capacity of a double-sided diskette is: 

(153 * 32 * 256) + (1 * 26 * 128) = 1,256,7)04 bytes 


The total capacity of a single-sided diskette is: 
(76 * 32 * 256 ) + (1 * 26 * 128) = 625,92)0 


HARD DISK 

The TRS-80 Hard Disk Drive is organized into 256 
"cylinders". Each cylinder is made up of four tracks that 
have the same radius on each of the four surfaces (4 * 256= 
1024 total tracks per hard disk). 
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Each track contains 34 sectors, numbered 1-34. Each sector 
contains 256 bytes. 

The total capacity of a hard disk is: 

(1024 * 34 * 256) = 8,912,896 bytes 
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DISK SPACE AVAILABLE TO USER 


TRSDOS-16 occupies approximately 31 tracks on the floppy 
diskette and approximately 32 tracks on the hard disk. 

Track 0 is reserved by the System on both the floppy and 
hard disk. The hard disk also reserves track 1 for 
diagnostics. 

The directory and alternate directory on both the floppy 
diskettes and hard disk reserve a certain number of tracks, 
determined by the size of the directories (the size is set 
by the FORMAT command). 

To determine the number of tracks these directories will 
consume, use this formula: 


Directory Space Formula 

Description 


# of filenames / 4 

to determine number 

of 

(round result up to 

sectors used by the 


next integer value) 

primary directory 


# of sectors / 32 (floppy) 

to determine number 

of 

# of sectors / 34 (hard) 

tracks used by the 


(round result up to 
next integer value) 

primary directory 



# of tracks * 2 to determine the total 

number of tracks used for 
the primary and alternate 
directories (the 
alternate directory is 
simply a copy of the 
primary directory) 


Note: TRSDOS-16 stores 4 filenames per sector in the 

directory. 
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For example, if you use this Format command: 

FORMAT :1 {PW=PASSWORD,SIZE=250} 


the directories will consume 

250 filenames / 4 
round up 

63 sectors / 32 (floppy) 
round up 

2*2 


a total of four tracks: 

= 62.5 

= 63 

= 1.96 

= 2 tracks for each 

directory 

= 4 total tracks used for 

the primary and alternate 
directories. 
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UNIT OF ALLOCATION 


All allocation of disk space is made by single sectors. 
This means that the smallest non-empty TRSDOS-16 file will 
consist of one sector. 


Single-Sided 


Diskette 

Tracks 

Sectors 

Bytes 

1 


76 

2,432 

622,592 



1 

32 

8,192 

.11! 


— 

1 

256 

Double-Sided 



1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

! 

1 

1 

1 

1 

I 

! 

1 

1 

! 

! 

Diskette Cylinders 

Tracks 

Sectors 

Bytes 

1 

76 

154 

4,896 

1,253,376 

— 

1 

2 

64 

16,384 

— 

— 

1 

32 

8,192 


” “ ■— 

— 

1 

256 

Note: Track 0 on the floppy diskette (only one 

side for 

double-sided 

diskettes) 

is reserved 

for System 

use and is 

not available 

for user 

storage. It 

is formatted 

single 

density with 

26 sectors 

that contain 128 bytes 

each. 

Hard Disk Cylinders 

Tracks 

Sectors 

Bytes 

1 

256 

1024 

34,816 

8,912,896 

— — “ 

1 

4 

136 

34,816 

™ “ 

- — 

1 

34 

8,704 



— 

1 

256 
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DISK FILES 


METHODS OF FILE ALLOCATION 

TRSDOS-16 provides two ways to allocate disk space for 
files: Dynamic Allocation and Pre-Allocation. 


DYNAMIC ALLOCATION 

With dynamic allocation, TRSDOS-16 allocates sectors only at 
the time of write. For example, when a file is first opened 
for output, no space is allocated. The first allocation of 
space is done at the first write. Additional space is added 
as required by subsequent writes. 

With dynamically allocated files, unused sectors are 
de-allocated (recovered) when the file is closed. 

Dynamic allocation is the method TRSDOS-16 uses, unless you 
execute the CREATE system command. 


PRE-ALLOCATION 

With pre-allocation, the file is allocated a specified 
number of sectors when it is created. Pre-allocated files 
can only be created by the system command CREATE. 

TRSDOS-16 will dynamically extend (enlarge) a pre-allocated 
file as needed. 

However, TRSDOS-16 will not de-allocate unused sectors when 
a pre-allocated file is closed. To reduce the size of a 
pre-allocated file you must copy it to a dynamically 
allocated file. The COPY system command does this 
automatically when the destination is a 
dynamically-allocated file. 
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RECORD LENGTH 


TRSDOS-16 transfers data to and from disks one sector at a 
time; i.e., in 256-byte blocks. These are the System's 
"physical" records. 

User records or "logical" records are the buffers of data 
you wish to transfer to or from a file. These can be from 1 
to 256 bytes long. 

The Operating System will automatically "block" your logical 
records into physical records which will be transferred to 
disk, and "de-block" the physical records into logical 
records which are used by your program. 

Therefore, your only concern during file-access is with 
logical records. You never need to worry about physical 
records, sectors, tracks, etc. This is to your benefit, 
since physical record lengths and features may change in 
later TRSDOS versions or with other peripheral devices, 
while the concept of logical records will not. 

From this point on, the term "record" refers to a "logical 
record". 


SPANNING 


If the record length is not an even divisor of 256, the 
records will automatically be spanned across sectors. 
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For example, if the record length is 200 , Sectors 1 and 2 
will look like this: 
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FIXED-LENGTH AND VARIABLE LENGTH RECORDS 


TRSDOS-16 files can have either fixed-length or 
variable-length records. Files with fixed-length records 
will be referred to as FLRs; files with variable length 
records, VLRs. 

Record length in an FLR file is set when the file is opened 
for the first time. This length can be any value from 1 to 
256 bytes. Once set, the record length in an FLR cannot be 
changed unless the file is being over-written with new data. 

The record-lengths in a VLR file can vary. For example, the 
first record in a file might have a length of 32; the 
second, 17; the third, 250; etc. 

The record length in a VLR file is specified in a one-byte 
length-field at the beginning of each record. The 
record-length byte indicates the entire length of the 
record, including the length-byte. This can be any value 
from 0 to 255. A value of 1 can be used to mean an empty 
record (e.g., a blank line in an ASCII text file). 


Length 

Byte Data 


0 


255 bytes of data 
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A length-byte value of 2 indicates that the record contains 
1 byte of data: 

Length 

Byte 



one byte of data 


A length-byte value of 16 indicates that the record contains 
15 bytes of data: 


Length 

Byte Data 


16 


15 bytes of data 
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RECORD NUMBERS 


Records are numbered from 0 (beginning of file) to 
16,777,214. 

A disk file can also contain up to 16,777,216 bytes of 
storage, however, your storage medium may not be capable of 
storing this much information. 

To determine the number of records a file will hold, use the 
following formula: 

16777216 / logical record length = number of records 


For example: 


16777216 / 38 = 441,505 records 


Example 

If a three megabyte file (possible with hard disk) is opened 
with a record length of 3 bytes, it would hold approximately 
1 , 000,000 records. 
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RECORD PROCESSING CAPABILITIES 

TRSDOS-16 allows both direct and sequential file access. 

Direct access — sometimes called "random access", allows 
you to process records in any sequence you specify. 

Sequential access allows you to process records in sequence: 
Record N, N+l, N+2,.... With sequential access, you do not 
specify a record number; instead, TRSDOS-16 accesses the 
record following the last record processed, starting with 
record 0 . 

FLR files may be opened as either direct access or 
sequential access. 

VLR files can only be opened as sequential access. You 
cannot position to a specific record in the file, since the 
varying record lengths make it impossible to calculate the 
position of the VLRs. 

The direct access SVC's are DIRRD (Direct-Read) and DIRWR 
(Direct-Write). Direct access SVC's always access the 
record you specify. 

The sequential access SVC's are READNX (Read-Next) and 
WRITNX (Write-Next). Sequential access SVC's always access 
the record following the last record processed. (When the 
file is first opened, sequential processing starts with 
record 0 , however DIRWR and DIRRD can be used to position to 
the EOF, end of file.) 


EXAMPLES WITH FIXED LENGTH FILES 

Assume you have a Fixed Length Record file currently open. 
Here are some typical sequences you can accomplish via the 
file processing routines. 

1. Read and/or write records in the file — in any order 
This is done using DIRRD and DIRWR SVC's. You could read 
record 5, write at end of file, read record 3, write record 
3, etc. 
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2. Sequential Read (or Write) beginning anywhere in the 
file. 


First you would do a direct-read to the record where you 
want to start reading or writing. After that, you would do 
sequential reads or writes until done (READNX and WRITNX). 
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3. Sequential Write starting at end of file. 

First do a direct-write to the end of the file. Then do 
sequential writes until done. 

4. Determine the number of records in a file. 

First do a direct-read to end of file, then use the LOCATE 
routine to get the current record number, which now equals 
number of records +1. 


EXAMPLES WITH VARIABLE LENGTH RECORDS 


Here are examples of ways to read or write VLR files: 

1. Start reading or writing sequentially at first record 
Open the file and start reading or writing sequentially 
until done. 

2. Sequential Write starting at end of file 

First do a direct-write to the end of the file. Then do 
sequential writes until done. 


Note: Whenever you write to a VLR, the end of the file is 

automatically reset to the last record you write. 

Also, you cannot update a VLR file directly. You must read 
in the file, update it and output the updated information to 
a new VLR file. 
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SUPERVISOR CALLS 


Supervisor Calls (SVCs) are operating system routines 
available to any user program. These routines alter certain 
system functions and conditions, provide file access, and 
perform I/O to the keyboard, video display, and printer. 

The available TRSDOS-16 SVCs are: 


KEYBOARD SVCs 

VIDEO SVCs 

KBCHAR 

CURSOR 

KBINIT 

VDCHAR 

KBLINE 

VDINIT 

VIDKEY 

VDLINE 


PRINTER 

SVCs 

SYSTEM 

CONTROL SVCs 

PRCHAR 


CLRXIT 

HLDKEY 

PRCTRL 


DATE 

JP2D0S 

PRINIT 


DOSCMD 

SETBRK 

PRLINE 


ERRMSG 

SETTRP 



ERROR 

VERSION 

MISCELLANEOUS SVCs 

FILE ACCESS SVCs 

DEBUG 

MOUNT 

CLOSE 

LOCATE 

DISMOUNT 

MOVBUF 

CLOSEF 

OPEN 

EXECUTE 

RESET 

DIRRD 

OPENDO 



DIRRW 

READNX 



DUMP 

RENAME 



KILL 

UNLOCK 



LOAD 

WRITNX 


COMMUNICATIONS SVCs 

ACTL 

BCTL 

ARCV 

BRCV 

ATX 

BTX 


RS232C 


Each SVC has a function code which you use to call it. 
These codes range from 0 to 512. 
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SVC BLOCK 

To use an SVC, you must assign it an area in memory called a 
BLOCK. You use this BLOCK to pass parameters to and from 
the SVC. 

The SVC block is a maximum of 16 words long. Each word 
consists of two bytes. 

These words are used to store parameters which you want to 
pass to or from the SVC. They are addressed by their 
byte-offset number, an even number ranging from 0 to 32. 

Some SVC's will use only one byte of a word. In this case 
the byte will be located in the low order 8-bits (or 
byte-offset +1). The high order 8-bits must contain 
zeroes. 

Certain parameters, such as memory addresses, will use two 
consecutive words of storage (called a long word). 

You can store an SVC BLOCK anywhere in memory; however, 
there must be a minimum of 32 bytes available after the 
starting address of the block, although the block may occupy 
less than last 32 bytes. 

Figure 5 is a sample SVC BLOCK. (DIRWR SVC — write a 
record out to disk.) 
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Byte-Offset 

+=====+ 



1 0-1 1 
+-+ 

< — 

TRSDOS SVC NUMBER 

1 2-3 | 

+ - + 

< — 

Error Code (Returned) 

1 4-5 | 

+-+ 

< — 

Reserved (must be 00 

1 6-7 | 

+-+ 

1 8-9 | 

< — 

File ID 

+-+ 

1 10-H | 

+-+ 

112-13| 

} 

Record Address 

+-+ 

114-15 j 
+=====+ 

} 

Record Number 


Figure 5. Sample SVC BLOCK 


In this illustration, each box represents a word. The 
numbers within the boxes are the byte-offset numbers for 
addressing the SVC BLOCK. 

The first number (the even number) is used to reference the 
offset. For example, byte-offset 0-1 contains the SVC 
number, but is addressed as offset 0. 

Byte-offsets 16 through 31 are not used for this SVC, and 
need not be present. 

The first three words of every SVC contain the same 
information: 

0-1 TRSDOS Function Code Number (for example, 35) 

2-3 On Error, returns the Error Code 
4-5 Reserved — Must contain zero 

If an area within a block is marked RESERVED, you must set 
it to zero or a parameter error will occur. 
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CALLING PROCEDURE 
To call a TRSDOS-16 SVC: 

1. Load the address of the desired SVC BLOCK into register 
A0. 

2. Execute a BRK #0 instruction. 

3. Upon return from an SVC f you must specifically TEST for 
for an error condition if you want to see if one 
exists. 

During the execution of an SVC f the SVC processor does not 
alter any registers, nor does it alter any status bits upon 
return. 

Figure 6 is part of a sample program for the DIRWR SVC. 

We'll look at it closely to see one of the ways to load a 
SVC BLOCK for execution. 

This sample assumes that the File Identification Number was 
previously stored in register Al, Record Address in register 
A2, and Record Number in register A3. 


WRITE LDA 

. A0, SVC BLOCK 

* 

line 

1 

MOVW 

@A0,#DIRWR SVC NUMBER 

* 

line 

2 

STW 

Al, 6 @ A0 

* 

line 

3 

STL 

A2,8@A0 

* 

line 

4 

STL 

A3,12@A0 

* 

line 

5 

BRK 

#0 

* 

line 

6 

TESTW 

2@A0 

* 

line 

7 

BNE 

• 

ERROR 

* 

line 

8 

• 

• 

SVC BLOCK 



line 


RDATAB 

32,0 

* 

9 

DIRWR SVC NUMBER 




10 

EQUW 

44 

* 

line 

Figure 6. 

Sample Program 
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In this program, 
into register AJ0. 


line 1 loads the address of the SVC BLOCK 


Line 2 moves the function code number to byte-offset 0 and 
line 3 stores the file identification number in 
byte-offset 6. 


Lines 4 and 5 store the Record Address and the Record Number 
in byte-offsets 8 and 12, respectively. Each is a long 
word. 


Line 6 executes the SVC. 

Line 7 tests for an error returned at offset 2. 

If there is an error, the return is non-zero and line 8 
either branches to an ERROR handling subroutine elsewhere in 
the program or executes the next line of the program. 

Line 9 defines the SVC BLOCK to 32 bytes of zeroes. 

And line 10 equates the SVC NUMBER to 44. 
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PROGRAMMING WITH USER INTERRUPTS 

TRSDOS-16 allows user-programmed interrupts as described 
under SETBRK and SETTRP. When the interrupt is received 
(that is, when the <BREAK> key is pressed or a system trap 
is taken), control transfers to your interrupt handling 
routine. 

When SETBRK terminates, or when an intercepted interrupt 
occurs, the following takes place: 

1. The current User PC and status registers are 
pushed on the USER stack. 

2. A branch is taken to the user-specified address. 


Before doing any processing, you should save any registers 
you plan to alter. When processing is complete, execute an 
RTR instruction (return with restore) to return to the 
interrupted program. 

A fatal error occurs if TRSDOS-16 cannot push three words 
onto the user stack, i.e., if the stack pointer contains a 
H'4 or less. 

NOTE: Interrupt handlers entered this way are also subject 

to interrupts. 


CONVERSION OF RELOCATABLE TO REAL ADDRESSES 

If a byte-offset of an SVC 'points' to a buffer in user 
memory, the following restrictions apply: 

All buffers are checked against their maximum possible 
sizes. It is not permissible to have a 256-byte buffer 
beginning 25 bytes from the end of memory. The check is 
made in this way: 

1. DATE SVC buffer requires 26 bytes 

2. ERRMSG SVC buffer requires 80 bytes 

3. OPEN SVC parameter list requires 5 bytes 
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4. Any call passing a filespec (KILL, RENAME, etc.) 
requires a 34-byte buffer 

5. Any Disk I/O call passing a buffer address is 
checked for a 256-byte buffer 

6. Any miscellaneous I/O calls (PRLINE, VDLINE, etc.) 
passing a fixed length buffer is checked 

for 256 bytes. 
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ACTL 

Control Channel A 


Function Code 100 


Performs control functions on serial channel A and then 
returns its status. 

TRSDOS-16 sets up A/BRCV, A/BTX and A/BCTL when you 
initialize channel A/B with RS232C. If you call any of 
these routines while the channel is not initialized 
(active), you will get an error return code of 1 (no 
function code exists). 


Entry Conditions 
Byte-offset 0-1 
6-7 


100 

option switch 


Exit Conditions 
Byte-offset 2-3 
8-9 


error code 

communications status code 


Valid option switch settings are: 

option Meaning 
switch 

0 Get status of serial channel into 

the Status Value 

1 Get received buffer count into the 
Status Value 

2 Turn on Request to Send (RTS) signal 

3 Turn off RTS 

4 Start transmission of a BREAK sequence 

5 Stop transmission of a BREAK sequence 

6 Clears receive buffer 

7 Reset SIO Error condition 
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The 8-bit grouping of 
status code are: 


flags returned in 


the communications 


Bit Meaning 


0 Clear to Send not present 

1 Unused 

2 Transmitter busy 

3 Modem data carrier not present 

4 Parity error in byte now being received 

5 Data overflow due to a byte now being 
received 

6 Framing error in a byte now being received 

7 Break Sequence now being received 


Example 


ACTL 

LDA 

.A0,SVC BLOCK 


MOVW 

@A0,#ACTL SVC NUMBER 


MOVW 

6@A0,#OPTION SWITCH 


BRK 

#0 


TESTW 

2@A0 


BNE 

• 

ERROR 

SVC BLOCK 

• 



RDATAB 

32,0 

ACTL SVC 

NUMBER 



EQUW 

100 


OPTION SWITCH 

EQUW 0 
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ARCV Function Code 96 

Channel A Receive 

Returns a single character from serial channel A. 

TRSDOS-16 sets up A/BRCV, A/BTX and A/BCTL when you 
initialize channel A/B with RS232C. If you call any of 
these routines while the channel is not initialized 
(active), you will get an error return code of 1 (no 
function code exists). 


INPUT BUFFER 

Each channel (A and B) has its own internal 16-character 
receive buffer to reduce overruns when receiving data at 
high speeds. This buffer is a First-In, First-Out buffer 
(FIFO) and is established when the channel is initialized. 

When a character is received by the ARCV and BRCV SVC's, it 
is stored in this buffer along with its status when it was 
received. 

Each time a new character is received into the buffer the 
character at the top of the buffer (oldest character) is 
pushed into the character returned byte-offset and its 
status (stored in the buffer when it was received) is pushed 
into the communications status code byte-offset. 

An overrun occurs only when the 17th character is received 
into the already-full buffer. The 16th character is 
replaced with the 17th. When the character that caused the 
overrun is retrieved into the character returned 
byte-offset, an overrun will be indicated in communication 
status code . 

If there are no characters "waiting" in the buffer, the 
communications status code will reflect the current status 
of the serial interface. 


Entry Conditions 
Byte-offset 0-1 96 
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Exit Conditions 
Byte-offset 2-3 
6-7 
8-9 
10-11 


error code 

character returned (if any) 
communications status code 

character received status 

0 = character received 
non-zero = character not received 


The 8-bit grouping of flags returned in the communications 
status code are: 


Bit Meaning 


0 Clear to Send not present 

1 Unused 

2 Transmitter busy 

3 Modem data carrier not present 

4 Parity error in byte now being received 

5 Data overflow due to a byte now being 
received 

6 Framing error in a byte now being received 

7 Break Sequence now being received 


Example 


ARCV 


LDA 

.A0,SVC BLOCK 

MOVW 

@A0,#ARCV SVC NUMBER 

BRK 

#0 

TESTW 

2@A0 

BNE 

ERROR 


SVC BLOCK 

RDATAB 32,0 

ARCV SVC NUMBER 

EQUW 96 
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ATX Function Code 97 

Channel A Transmit 


Outputs a single character to serial channel A. 

TRSDOS-16 sets up A/BRCV, A/BTX and A/BCTL when you 
initialize channel A/B with RS232C. If you call any of 
these routines while the channel is not initialized 
(active), you will get an error return code of 1 (no 
function code exists). 

Data bytes will be transmitted even if no carrier is 
present. You must check the communication status code and 
character transmitted status for error conditions. 


Entry Conditions 
Byte-offset 0-1 97 

6-7 character to be sent 


Exit Conditions 
Byte-offset 2-3 
8-9 


10-11 


error code 

communications status code 

character transmitted status 

0 = character transmitted 
non-zero = character not transmitted 


The 8-bit grouping of flags returned in the communications 
status code are: 

Bit Meaning 


0 Clear to Send not present 

1 Unused 

2 Transmitter busy 

3 Modem data carrier not present 

4 Parity error in byte now being received * 

5 Data overflow due to a byte now being 

received * 

6 Framing error in a byte now being received * 

7 Break Sequence now being received * 


* Bits 4-7 are only used when the character was not 
sent 
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Example 


• 

ATX LDA 

MOVW 
MOVW 
BRK 
TESTW 
BNE 


• 

SVC BLOCK 

RDATAB 32,0 

ATX SVC NUMBER 

EQUW 97 

CHAR TO SEND 

TEXT 'G 


. AJ0 , SVC BLOCK 
@AJ0,#ATX SVC NUMBER 
6@AJ0,#CHAR TO SEND 

#J0 

2@AjEf 

ERROR 
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TRS-8Q 


BCTL Function Code 101 

Control Channel B 


Performs control functions on serial channel B and then 
returns its status. 

Entry Conditions 


Byte-offset 0-1 

101 

6-7 

option switch 

Exit Conditions 

Byte-offset 2-3 

error code 

8-9 

comunication status code 


Valid option switch settings are: 

Option Meaning 

Switch 


0 Get status of serial channel into 

the Status Value 

1 Get received buffer count into the 
Status Value 

2 Turn on Request to Send (RTS) signal 

3 Turn off RTS 

4 Start transmission of a BREAK sequence 

5 Stop transmission of a BREAK sequence 

6 Clears receive buffer 

7 Reset SIO Error condition 


The 8-bit grouping of flags returned in the communications 
status code are: 

Bit Meaning when set 


0 Clear to Send not present 

1 Unused 

2 Transmitter busy 

3 Modem data carrier not present 
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Bit Meaning when set 


4 Parity error in byte now being received 

5 Data overflow due to a byte now being 
received 

6 Framing error in a byte now being received 

7 Break Sequence now being received 


Example 


BCTL 

LDA 

. AJ0, SVC BLOCK 


MOVW 

@AJ0,#BCTL SVC NUMBER 


MOVW 

6@AJ0, # OPT ION SWITCH 


BRK 

#J0 


TESTW 

2@A0 


BNE 

• 

ERROR 

SVC BLOCK 

• 



RDATAB 

32 ,0 

BCTL SVC 

NUMBER 



EQUW 

101 

OPTION SWITCH 



EQUW 

0 
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BRCV Function Code 98 

Channel B Receive 

Returns a single character from serial channel B. 

TRSDOS-16 sets up A/BRCV, A/BTX and A/BCTL when you 
initialize channel A/B with RS232C. If you call any of 
these routines while the channel is not initialized 
(active), you will get an error return code of 1 (no 
function code exists). 



INPUT BUFFER 

Each channel (A and B) has its own internal 16-character 
receive buffer to reduce overruns when receiving data at 
high speeds. This buffer is a First-In, First-Out buffer 
(FIFO) and is established when the channel is initialized. 

When a character is received by the ARCV and BRCV SVC's, it 
is stored in this buffer along with its status when it was 
received. 

Each time a new character is received into the buffer the 
character at the top of the buffer (oldest character) is 
pushed into the character returned byte-offset and its 
status (stored in the buffer when it was received) is pushed 
into the communications status code byte-offset. 

An overrun occurs only when the 17th character is received 
into the already-full buffer. The 16th character is 
replaced with the 17th. When the character that caused the 
overrun is retrieved into the character returned 
byte-offset, an overrun will be indicated in communication 
status code . 

If there are no characters "waiting" in the buffer, the 
communications status code will reflect the current status 
of the serial interface. 


Entry Conditions 
Byte-offset 0-1 98 
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Exit Conditions 
Byte-offset 2-3 
6-7 
8-9 
10-11 


error code 

character returned (if any) 
communications status code 

character received status 

0 = character received 
non-zero = character not received 


The 8-bit grouping of flags returned in the communication 
status code are: 


Bit Meaning 


0 Clear to Send not present 

1 Unused 

2 Transmitter busy 

3 Modem data carrier not present 

4 Parity error in byte now being received 

5 Data overflow due to a byte now being 
received 

6 Framing error in a byte now being received 

7 Break Sequence now being received 


Example 


BRCV 


LDA 

.A0,SVC BLOCK 

MOVW 

@A0,#BRCV SVC NUMBER 

BRK 

#0 

TESTW 

2@A0 

BNE 

ERROR 


SVC BLOCK 

RDATAB 32,0 

BRCV SVC NUMBER 

EQUW 98 
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BTX Function Code 99 

Channel B Transmit 


Outputs a single character to serial channel B. 

TRSDOS-16 sets up A/BRCV, A/BTX and A/BCTL when you 
initialize channel A/B with RS232C. If you call any of 
these routines while the channel is not initialized 
(active), you will get an error return code of 1 (no 
function code exists). 

Data bytes will be transmitted even if no carrier is 
present. You must check the communication status code and 
character transmitted status for error conditions. 


Entry Conditions 
Byte-offset 0-1 99 

6-7 character to be sent 


Exit Conditions 
Byte-offset 2-3 
8-9 


10-11 


error code 

communications status code 

character transmitted status 

0 = character transmitted 

non-zero = character not transmitted 


The 8-bit grouping of flags returned in the communications 
status code are: 


Bit Meaning 


0 Clear to Send not present 

1 Unused 

2 Transmitter busy 

3 Modem data carrier not present 

4 Parity error in byte now being received * 

5 Data overflow due to a byte now being 

received * 

6 Framing error in a byte now being received * 

7 Break Sequence now being received * 


* Bits 4-7 are only used when the character was not 
sent 
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® 


Example 


• 

BTX LDA 

MOVW 
MOVW 
BRK 
TESTW 
BNE 


SVC BLOCK 

RDATAB 32,0 

BTX SVC NUMBER 

EQUW 99 

CHAR TO SEND 

TEXT ' G 


. AJ0, SVC BLOCK 
@AJ0,#BTX SVC NUMBER 
6@A0,#CHAR TO SEND 
#0 

2@A0 

ERROR 
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TRS-80 


CLOSE Function Code 42 

Close Disk Files 


Terminates output to a specified file. This SVC first 
writes all unsaved data to disk, then updates the directory. 


Entry Conditions 
Byte-offset 0-1 42 

6-7 file identification number 


Exit Conditions 

Byte-offset 2-3 error code 

The file identification number is a unique number assigned 
to each file when it is opened. 

Example 

In this example the file identification number was 
previously stored in register Al. 


CLOSE 


• 

LDA . A0, SVC BLOCK 

MOVW @A0,#CLOSE SVC NUMBER 

STW .Al,6@A0 

BRK #0 

TESTW 2@A0 

BNE ERROR 


• 

SVC BLOCK 

RDATAB 32,0 

CLOSE SVC NUMBER 

EQUW 42 
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CLOSEF 
Close Files 


Function Code 133 


Closes all open files, except for a currently executing 
DO-file, SPOOL file, or a file opened by OPENDO. 


Entry Conditions 
Byte-offset 0-1 133 


Exit Conditions 

Byte-offset 2-3 error code 


Example 


CLOSEF 

LDA 

. AJ0, SVC BLOCK 


MOVW 

@AJE(, #CLOSEF SVC NUMBER 


BRK 

#J0 


TESTW 

2@AJ0 


BNE 

• 

ERROR 

SVC BLOCK 

• 



RDATAB 

32 ,0 

CLOSEF SVC NUMBER 



EQUW 

265 
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TRS-80 


CLRXIT Function Code 257 

Clear User Memory and Jump to TRSDOS-16 


Clears (writes binary zeroes) to user memory, then gives 
control to TRSDOS-16 Ready. If used with a DO-File, control 
proceeds to the next command in the DO-File. 


Entry Conditions 
Byte-offset 0-1 257 


Exit Conditions 

Byte-offset 2-3 error code 

Example 


CLRXIT 


• 

LDA 

MOVW 

BRK 


.A0,SVC BLOCK 

@A0,#CLRXIT SVC NUMBER 

#0 


• 

SVC BLOCK 

RDATAB 32,0 

CLRXIT SVC NUMBER 

EQUW 257 
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TECHNICAL INFORMATION 


CURSOR Function Code 10 

Position Cursor 


Positions the cursor to specified screen coordinates. This 
routine treats ROW and COLUMN as Modulo 24 and Modulo 80 , 
respectively. 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-9 


10 

row to position cursor 
column to position cursor 


Exit Conditions 

Byte-offset 2-3 error code 


Example 


• 

• 

CURSOR LDA 

. AJ0, SVC BLOCK 

MOVW 

@AJ0, ICURSOR SVC NUMBER 

MOVW 

6@AJ0,#ROW POSITION 

MOVW 

8@AJ0, #COLUMN POSITION 

BRK 

#J0 

TESTW 

2@A0 

BNE 

• 

ERROR 

SVC BLOCK 

RDATAB 

32 ,0 

CURSOR SVC NUMBER 

EQUW 

10 

ROW POSITION 

EQUW 

12 

COLUMN POSITION 

EQUW 

40 
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DATE 

Return Date String 


Function Code 45 


Returns the time and date as a 26-byte ASCII string with 
eight fields. 


CONTENTS OF TIME/DATE STRING (SAMPLE) 


|s A 

T | 

1 

1 

i a* 

i 

i < 

2 8 |1 

9 7 9| 

|1 1 8 |1 3 

.20. 

1 1 

£» 1 
1 

to 1 

1 

1 

1 

i _ i 

1 5 | 

1 

NAME 

DAY 

OF 

i 

MON. 

1 

DAY OF 
MON. 

1 

YEAR 

1 

DAY OF 

YEAR 

1 

TIME 

1 

MON. 

# 

1 

DAY 

OF WEEK 


For example: 

SATAPR28197911813.20.42045 

represents the data "Saturday, April 28, 1979, the 118th day 
of the year, 13:20:42 hours, the fourth month of the year, 
the fifth day of the week". 

Monday is considered day 0. The date calculations are based 
on the Julian Calendar. 


Entry Conditions 
Byte-offset 0-1 45 

6-9 address of 26-byte buffer 


Exit Conditions 

Byte-offset 2-3 error code 


Example 


DATE 


LDA .A0,SVC BLOCK 

MOVW @A0,#DATE SVC NUMBER 

LDA .Al,DATE BUFFER 

STL .Al,6 @A0 

BRK #0 

TESTW 2@A0 
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BNE ERROR 


SVC 

BLOCK 



RDATAB 

32,0 

DATE 

SVC NUMBER 



EQUW 

45 

DATE 

BUFFER 



RDATAB 

26,0 
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DEBUG 

Load the Debugger 


Function Code 259 


Turns the debugger on and off. This call is valid only if 
DEBUG was configured. See Appendix B of this section for 
more information on the Configuration Command File. 


Entry Conditions 
Byte-offset 0-1 259 

6-7 function code 


Exit Conditions 

Byte-offset 2-3 error code 


Valid function codes are: 


FUNCTION CODE 

FUNCTION 

0 

Turns DEBUG off 

1 

Turns DEBUG on 

2 

Enters DEBUG 


If you use function code 2, the Debugger will load with the 
PC register set to the current instruction address plus two. 


Example 


DEBUG 


LDA 

.A0,SVC BLOCK 

MOVW 

@A0,#DEBUG SVC NUMBER 

MOVW 

6@A0 f #DEBUG ON 

BRK 

#0 

TESTW 

2@A0 

BNE 

ERROR 


Radio /hack 


147 
















TRSDOS 16 OWNER'S MANUAL 


TRS-80 


TECHNICAL INFORMATION 



SVC BLOCK 





RDATAB 

32 ,0 

DEBUG 

SVC 

NUMBER 

EQUW 

259 

DEBUG 

ON 

EQUW 

1 
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DIRRD 

Direct Read 


Function Code 35 


Reads a specified record of an FLR (fixed-length record) 
file. 

If you have a VLR (variable-length record) file, you can use 
DIRRD to read only the first record (. 0 ) or the end of file 
(- 1 ). 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-11 
12-15 


16 


35 

file identification number 

record buffer address 

record number 

0 = position to beginning of file 
H'FFFFFFFF = position to end of file 
record lock flag 


Exit Conditions 

Byte-offset 2-3 error code 


The file identification number is a unique number assigned 
to each file when it is opened. 

The record buffer address is a 32 bit address that points 
to the beginning of a 256-byte Record Buffer; that is where 
the record will be placed after the disk read. 

The record number is a 32 bit number specifying the 
desired record number. 

If the record lock flag is non-zero, the specified record 
remains locked until the user program performs an UNLOCK on 
the record. 

If the record lock flag is zero, the record is not locked. 
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Example 

Before executing this program, store the File Identification 


Number 

in 

register 

Al and the 

Record Number 

READ 


• 

• 

LDA 

. A0, SVC BLOCK 



MOVW 

@AJ0,#DIRRD 

SVC NUMBER 



STW 

.Al,6@A0 




LDA 

•A2,RECORD 

BUFFER 



STL 

. A2,8@A0 




STL 

• A3,12@A0 




BRK 

#0 




TESTW 

2@A0 




BNE 

• 

ERROR 


SVC BLOCK 

• 

• 





RDATAB 

32,0 


DIRRD SVC 

NUMBER 





EQUW 

35 


RECORD 

BUFFER 





RDATAB 

256,0 
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TRS-80 


DIRWR Functon Code 44 

Direct Write 

Writes a specified record in an FLR (fixed length record) 
file. 

With a VLR (variable length record) files, you can use DIRWR 
to write only the first record (0) or the end of the file 
(- 1 ). 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-11 
12-15 


44 

file identification number 

record buffer address 

record number 

0 = position to beginning of file 
H•pFFFFFFF = position to end of file 


Exit Conditions 

Byte-offset 2-3 error code 


The file identification number is a unique number assigned 
to each file when it is opened. 

The record buffer address is a 32-bit address that points 
to the beginning of a 256-byte Record Buffer; that is where 
the record will be placed after the disk read. 

The record number is a 32-bit number specifying the 
desired record number. 


Example 

Before executing this program, store the Identification 
Number in register Al, Record Address in register A2, and 
Record Number in register A3. 


WRITE LDA 

MOVW 


. AJ0, SVC BLOCK 

@A0,#DIRWR SVC NUMBER 
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STW 

. Al, 6@AJ0 

LDA 

.A2,RECORD BUFFER 

STL 

.A2,8@AJ0 

STL 

.A3,12@AJ0 

BRK 

#J0 

TESTW 

2@AJ0 

BNE 

• 

ERROR 

• 

• 

SVC BLOCK 

RDATAB 

32,0 

DIRWR SVC NUMBER 

EQUW 

44 

RECORD BUFFER 

RDATAB 

256,0 
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DISMOUNT Function Code 139 

Dismount Disk 


Logically disconnects a MOUNTed disk device. This command 
is valid for drives 0-3 and 5-7 for hard disk users and 
drives 1-3 for floppy disk users. The system disk may not 
be DISMOUNTed. 

A DISMOUNT/MOUNT sequence is required for each diskette 
swap. (see Chapter 1) 

You should make sure all files are closed before executing a 
DISMOUNT/MOUNT sequence 

Entry Conditions 
Byte-offset 0-1 
6-9 


Exit Conditions 
Byte-offset 2-3 


139 

device name 


error code 


Valid device names are: FDJ80 = floppy drive 0 

FDj3l = floppy drive 1 

FDJ02 = floppy drive 2 

FD03 = floppy drive 3 

HDJ00 = hard drive 4 

HD01 = hard drive 5 

HDJ32 = hard drive 6 

HDJ03 = hard drive 7 


Example 



DISMNT 

• 

• 

LDA 

. AJ0, SVC BLOCK 


MOVW 

@AJ0 f #DISMNT SVC NUMBER 


LDA. 

.Al,DEVICE NAME 


MOVL 

6@A0,@A1 


BRK 

#J0 


TESTW 

2@AJ0 


BNE 

ERROR 
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TRS-80 


SVC BLOCK 

RDATAB 32,0 

DISMNT SVC NUMBER 

EQUW 139 

DEVICE NAME 

TEXT 'FD01' 
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DOSCMD Function Code 270 

Execute TRSDOS-16 Command 

Passes a command string to the TRSDOS-16 Ready mode for 
execution. After execution is complete, control returns to 
TRSDOS-16 Ready. 

This command alters the buffer used by the MOVBUF SVC. 

When chaining programs, do not use DOSCMD to execute the 
programs. Use EXECUT instead. 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-11 


270 

length of string 

address of string 


Exit Conditions 

Byte-offset 2-3 error code 


Example 


DOSCMD LDA 
MOVW 
MOVW 
LDA 
STL 
BRK 


.A0,SVC BLOCK 
@A0,#DOSCMD SVC NUMBER 
6@A0,#STRING LENGTH 
.Al,STRING 
. Al,8 @A0 
#0 


SVC BLOCK 

RDATAB 


DOSCMD SVC NUMBER 
EQUW 

STRING LENGTH 
EQUW 

STRING 

TEXT 


32,0 

270 

5 

'DIR 3' 
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DOM 1 * Function Code 130 

Dump Memory to Disk 


Writes a 68000 format program from memory to diskette. The 
Dump replaces any existing file with the same name. 


Entry Conditions 
Byte-offset 0-1 
6-9 
10-13 
14-17 
18-21 
22-25 


Exit Conditions 
Byte-offset 2-3 


130 

filespec address 
start dump address 

end dump address 
relocation address 

transfer Address 


error code 


filespec address specifies the memory location of a 
standard TRSDOS-16 file specification. The filename is an 
ASCII string terminated by a carriage return. 

start dump address and end dump address are the 
beginning and ending locations in memory where the program 
resides. 

relocation address is the starting location where you want 
the file to load. If you don't want to relocate the file, 
set the relocation address at 0. 

transfer address is the program entry point (the address 
of the first instruction to execute). If you specify a 
relocation address , this address offsets the transfer 
address . 

Note: all addresses must be an even value. 


Example 


DUMP 


LDA .A0,SVC BLOCK 

MOVW @A0,DUMP SVC NUMBER 
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LDA .Al f FILE NAME 

STL .A1,6@AJ0 

MOVL 10@ A0,#START AND TRANS ADDRESS 

MOVL 14@A0 / #END DUMP ADDRESS 

MOVL 18@A0, #RELOCATION ADDRESS 

MOVL 22@A0, #START AND TRANS ADDRESS 

BRK #0 

TESTW 2@A0 

BNE ERROR 



• 

SVC BLOCK 

RDATAB 32,0 

DUMP SVC NUMBER 

EQUW 130 

FILE NAME 

TEXT 'TEST/SRC' 

DATAB H'0D 

START AND TRANS ADDRESS 

EQUL H'60000 

END DUMP ADDRESS 

EQUL H'60000 

RELOCATION ADDRESS 

EQUL 0 


( 
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ERRMSG Function Code 52 

Error Message 


In response to a requested error number, this routine 
returns an 80-byte descriptive error message to a specified 
buffer area. 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-11 


52 

error number 
message buffer address 


Exit Conditions 

Byte-offset 2-3 error code 


The error number range is 0 to 255, inclusive. 


Example 


ERRMSG 

LDW 

. Al, 2@A0 



LDA 

. A0, SVC BLOCK 


MOVW 

@A0, #ERRMSG 

SVC NUMBER 


STW 

. Al, 6 @ A0 



LDA 

.Al,MESSAGE 

BUFFER 


STL 

. Al, 8@A0 



BRK 

#0 



TESTW 

2@A0 



BNE 

JP2D0S 



CALL 

• 

VIDEO PRINT 

LINE ROUT 11 

• 

SVC BLOCK 




RDATAB 

32,0 


ERRMSG 

SVC NUMBER 




EQUW 

52 


MESSAGE 

BUFFER 




RDATAB 

80,0 



Radio /hack 


158 











TRSDOS 16 OWNER'S MANUAL 


TECHNICAL INFORMATION 


ERROR Function Code 39 

Display Error Number 

Displays the message ERROR followed by the specified error 
code at the current cursor position. 


Entry Conditions 
Byte-offset 0-1 39 

6-7 error number 


Exit Conditions 

Byte-offset 2-3 error code 

The error number is a 0 - 255 code of the message you want 
displayed. 


Example 



ERROR 

• 

LDW 

.A1,2@AJ0 


LDA 

. AJ0 , SVC BLOCK 


MOVW 

@AJ0,#ERROR SVC NUMBER 


STW 

.Al , 6@A0 


BRK 

#J0 


TESTW 

2@AJ0 


BNE 

JP2D0S 


SVC BLOCK 

RDATAB 3 2 ,0 

ERROR SVC NUMBER 

EQUW 39 
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EXECUT 

Execute Program 


Function Code 263 


Begins program execution in user memory. 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-11 


263 

00 (Reserved) 
filespec address 


Exit Conditions 

Byte-offset 2-3 error code 


The filespec address is the 32-bit address of a valid 
TRSDOS-16 filespec terminated by a carriage return. 


Example 


• 

EXECUTE LDA 
MOVW 
MOVW 
LDA 
STL 
BRK 
TESTW 
BNE 


. A0 ,SVC BLOCK 

@AJ0, #EXECUTE SVC NUMBER 

6@A0,#00 

.Al,FILENAME 

. A1,8@AJ0 

#J0 

2@AJ0 

JP2D0S 


SVC BLOCK 

RDATAB 

EXECUTE SVC NUMBER 
EQUW 

FILENAME 


TEXT 

DATAB 


32,0 

263 

'TEST/CMD' 
H' J0D 
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HLDKEY Function Code 29 

Enable Hold Key 


Suspends and restarts terminal output whenever you press the 
<HOLD> key. 

This SVC must first be enabled. Then you must periodically 
call HLDKEY to check if the <HOLD> key has been depressed. 
This places the program in control of the pause checking. 

Note that execution of certain DOSCMDs might alter the 
HLDKEY status. This will happen if the TRSDOS-16 command 
issues HLDKEY requests. 


Entry Conditions 
Byte-offset 0-1 
6-7 


29 

function code 


Exit Conditions 

Byte-offset 2-3 error code 


The HLDKEY function codes are: 
Code Meaning 


0 Turn off HOLD processor. Pressing <HOLD> 

generates H'00'. 

1 Turn on HOLD processor. <HOLD> key doesn't 
generate keyboard data, it is intercepted 
by TRSDOS-16. 

2 Check for <HOLD> key. If pressed, wait until 
pressed again. 


Example 


HLDKEY LDA .A0,SVC BLOCK 

MOVW @A0,#HLDKEY SVC NUMBER 

MOVW 6@A0,#HOLD KEY FUNCTION CODE 
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BRK 

TESTW 

BNE 

* CHECK TO SEE IF 
LDA 
MOVW 
MOVW 
BRK 
TESTW 
BNE 


SVC BLOCK 

RDATAB 

HDLKEY SVC NUMBER 
EQUW 

HOLD KEY FUNCTION 
EQUW 

CHECK IF HOLD KEY 
EQUW 


TRS-80 ® 


#J0 

2@AJ0 

ERROR 

HOLD KEY PRESSED 
. AJ0, SVC BLOCK 
@AJ0,#HLDKEY SVC NUMBER 
6@AJ0,#CHECK IF HOLD KEY WAS PRESSED 
#J0 

2@AJ0 

ERROR 


32,0 

29 

CODE 

1 

PRESSED 

2 
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JP2DOS Function Code 264 

Jump to TRSDOS-16 


After closing all open files and performing system 
housekeeping, returns control to TRSDOS-16 Ready. 

If a program under the control of a DO-file executes this 
routine, control proceeds to the next command in the 
DO-file. 


Entry Conditions 
Byte-offset 0-1 264 

6-7 00 (Reserved) 


Exit Conditions 

Byte-offset 2-3 error code 

Example 


JP2D0S LDA 
MOVW 
BRK 


SVC BLOCK 

RDATAB 32, J0 

JP2D0S SVC NUMBER 

EQUW 264 


. AJ0, SVC BLOCK 

@AJ0, # JP2D0S SVC NUMBER 

#J0 
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KBCHAR 

Keyboard Character 


Function Code 4 


Checks the keyboard for a new character entry. 

If characters are present in the key-ahead buffer, the first 
character in the buffer will be returned in the returned 
character byte-offset. 

The <BREAK> key is masked from the user — it will never be 
returned, since it is intercepted by the System. If a 
SETBRK routine is enabled, control passes to the processing 
program (see SETBRK) whenever <BREAK> is pressed. 

Otherwise, control will pass to TRSDOS-16 Ready. 


Entry Conditions 
Byte-offset 0-1 4 

6-7 wait for character flag 


Exit Conditions 
Byte-offset 2-3 
6-7 
8-9 


error code 

character present flag 

returned character 


If you want the SVC to return only when a character is 
detected, set the wait for character flag to non-zero. A 
zero in this byte-offset causes the SVC to return, with or 
without a character, immediately after the keyboard buffer 
is checked. 

A character present flag of non-zero means the routine has 
returned with a valid ASCII character in the returned 
character position. 

If it returns without a character, (when the SVC is set not 
to wait for a character) the routine clears the character 
present flag , but doesn't change the contents of the 
returned character byte-offset. 
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Example 

This program returns the character most recently pressed and 
then calls PRINT CHARACTER ROUTINE, which uses either the 
VDCHAR or PRCHAR routines to print it. 


KBCHAR 

• 

LDA 


MOVW 


MOVW 


BRK 


TESTW 


BNE 


CALL 


. AJ0, SVC BLOCK 

@A0, #KBCHAR SVC NUMBER 

6@A0, #WAIT FOR CHARACTER FLAG 

#0 

2@A0 

ERROR 

PRINT CHARACTER ROUTINE 


SVC BLOCK 

RDATAB 32,0 

KBCHAR SVC NUMBER 

EQUW 4 

WAIT FOR CHARACTER FLAG 
EQUW 1 
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KBINIT Function Code 1 

Keyboard Initialize 


Initializes the keyboard input driver. You might want to 
call this SVC before starting keyboard input to clear 
previous keystrokes and the key-ahead buffer. TRSDOS-16 
does this automatically at start-up. 


Entry Conditions 
Byte-offset 0-1 1 


Exit Conditions 

Byte-offset 2-3 error code 


Example 


• 

KBINIT LDA 
MOVW 
BRK 
TESTW 
BNE 


SVC BLOCK 

RDATAB 32,0 

KBINIT SVC NUMBER 

EQUW 1 


.A0,SVC BLOCK 
@A0,#KBINIT SVC NUMBER 
#0 

2@A0 

ERROR 
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KBLINE Function Code 5 

Keyboard Line 


Inputs a line from the keyboard to a buffer and echoes the 
line to the Display, starting at the current cursor 
position. As it receives and displays each character, the 
routine advances the cursor to the next position. 

When you enter this routine, the input buffer contains a 
string of periods which it sends to the display. This 
string is for your convenience to indicate the length of the 
input field. 

The keyboard line ends when you press <ENTER> or when the 
routine fills the input buffer. When you terminate line 
input, the routine always sends a carriage return and an 
erase-to-end-of-screen command to the Display. It stores a 
carriage return as a character input only if you actually 
press <ENTER>. 

If you type a control code not listed below, the routine 
places it in the buffer and represents it on the display 
with the + symbol. 


KEY 

HEX 

CODE 

FUNCTION 

BACKSPACE 

08 

Backspaces the cursor and erases a 
character. 

ENTER 

0D 

Terminates line. Clears trailing 
periods on Display 

CTRL W 

17 

Fills remainder of input buffer with 
blanks, blanks remainder of Display line 

CTRL X 

18 

Fills remainder of input buffer with 
blanks, blanks to end of Display. 

ESC 

IB 

Reinitializes input function by filling 
input buffer with periods and restoring 
cursor to original position. 

<- 

1C 

Backspaces the cursor to allow editing of 
line. Does not erase characters. 

-> 

ID 

Advances the cursor to allow editing of 
line. Does not erase characters. 
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Entry Conditions 
Byte-offset 0-1 5 

6-7 maximum number of characters to 

receive (0 - 255) 

8-11 input buffer address 


Exit Conditions 

Byte-offset 2-3 error code 

12-13 actual number of characters input 

14-15 terminating character of input 

H'0D if line was terminated with 

a carriage return, 0 if buffer 
was filled without a carriage 
return 


Example 


• 

KBLINE LDA 
MOVW 
MOVW 
LDA 
STL 
BRK 
TESTW 
BNE 


. AJ0, SVC BLOCK 
@A0,#KBLINE SVC NUMBER 
6 @A0, #MAXIMUM INPUT COUNT 
.Al,KEYBD BUFFER 
. Al, 8@A0 
#0 

2@A0 

ERROR 


• 

SVC BLOCK 

RDATAB 32,0 

KBLINE SVC NUMBER 

EQUW 5 

MAXIMUM INPUT COUNT 

EQUW 80 

KEYBD BUFFER 

RDATAB 80,0 
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KILL 

Delete File from Directory 


Function Code 41 


Deletes the specified file from the directory. A file must 
be closed for you to KILL it. 


Entry Conditions 
Byte-offset 0-1 
6-9 


41 

filespec address 


Exit Conditions 
Byte-offset 2-3 


error code 


The filespec address is the 32-bit address of a valid 
TRSDOS-16 filespec terminated by a carriage return. 


Example 


KILL 


• 

• 

LDA 

.A0,SVC BLOCK 



MOVW 

@A0,#KILL SVC 



LDA 

.Al f FILE NAME 



STL 

.Al,6 @A0 



BRK 

#0 



TESTW 

2@A0 



BNE 

• 

ERROR 

SVC BLOCK 

• 




RDATAB 

32,0 

KILL 

SVC NUMBER 




EQUW 

41 

FILE 

NAME 

TEXT 

'TEST/SRC' 



DATAB 

H'0D 
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LOAD 


Function Code 131 


LOAD'S a 68000 program into user memory. 


Entry Conditions 
Byte-offset 0-1 
6-9 
10-13 


14-17 


Exit Conditions 
Byte-offset 2-3 

10-13 

14-17 

18-21 


131 

filespec address 
low bound address (only if 
program is position independent, 
otherwise must be zero) 
high bound address (only if 
program is position independent, 
otherwise zero allows all of 
memory) 


error code 

start load address 

address of last byte loaded 

transfer address 


Supply a low bounds address and high bounds address only 
if your program does NOT have any absolute memory references. 

filespec address is the 32-bit address of a valid 

TRSDOS-16 program filespec terminated by a carriage return. 

low bounds address is the logical address you want the 
program loaded at. Specifying zero means the entire user 
memory is available. If this number is non-zero then the 
program MUST be position-independent. 

high bounds address is the logical address of the last 
byte available for the program being loaded. Specifying 
zero allows entire user memory. 

start load address is the location in memory of the first 
byte loaded. 

address of last byte loaded is the highest address of the loaded 
program. 
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transfer address is the program entry point (address of 
first instruction to be executed). If the program is 
nonexecutable ("load-only"), the byte-offset contains a -1 

Note: all addresses must be an even value. 


Example 


LOAD 

o 

LDA 

. A0 ,SVC BLOCK 


MOVW 

@A0,#LOAD SVC NUMBER 


LDA 

.Al,FILE NAME 


STL 

. Al,6 @A0 


BRK 

#0 


TESTW 

2@A0 


BNE 

ERROR 


SVC BLOCK 

RDATAB 32,0 

LOAD SVC NUMBER 

EQUW 131 

FILE NAME 

TEXT 'TEST/SRC' 

DATAB H'0D 
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LOCATE Function Code 33 

Locate Record 


Returns the number of the current record, i.e., the last 
record accessed. You can call this routine only with FLR 
(fixed-length Record) files. 


Entry Conditions 


Byte-offset 0-1 

33 


6-7 

file identification number 

Exit Conditions 



Byte-offset 2-3 

error code 


8-11 

record number 


The file identification 

number is a unique number 

assigned 

to each file when it is 

opened. 


The record number is a 

32 bit number specifying the 

desired record number. 

The record number will be 

zero if 


the file was just opened. 


Example 

Prior to execution of this routine, store the file 
identification number in register Al. 


• 

LOCATE LDA 
MOVW 
STW 
BRK 
TESTW 
BNE 


. AJ0, SVC BLOCK 

@AJ0, # LOCATE SVC NUMBER 

. Al, 6@AJ0 

#J0 

2@AJ0 

ERROR 


SVC BLOCK 

RDATAB 32 ,0 

LOCATE SVC NUMBER 

EQUW 33 
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MOUNT Function Code 138 

Mount Device 


Logically connects a device to the system. The system 
cannot access an unMOUNTed device. You must mount a 
diskette prior to any I/O attempts. 

A DISMOUNT/MOUNT sequence is required for each floppy 
diskette swap. 

You should make sure all files are closed before executing a 
DISMOUNT/MOUNT sequence. 

Entry Conditions 
Byte-offset 0-1 138 

6-9 device name 


Exit Conditions 

Byte-offset 2-3 error code 


Valid device names are: 


Example 


FD00 = floppy drive 0 
FD01 = floppy drive 1 
FD02 = floppy drive 2 
FD03 = floppy drive 3 
HD00 = hard drive 4 
HD01 = hard drive 5 
HD02 = hard drive 6 
HD03 = hard drive 7 


MOUNT 


LDA . A0, SVC BLOCK 

MOVW @A0, #MOUNT SVC NUMBER 

LDA .Al,DEVICE NAME 

MOVL 6@A0, @Al 

BRK #0 

TESTW 2@A0 

BNE ERROR 
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SVC BLOCK 

RDATAB 32,0 

MOUNT SVC NUMBER 

EQUW 138 

DEVICE NAME 

TEXT ' FDJZfl' 
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MOVBUF 
Move Buffer 


Function Code 267 


Either retrieves or stores an 80-byte buffer outside the 
user's memory. This buffer serves two purposes: 

1. To pass parameters when chaining two machine 
language programs. 

(When chaining programs, do not use DOSCMD to 
execute the programs. Use EXECUT instead.) 

2. To retrieve a TRSDOS-16 command line. When 
TRSDOS-16 starts a user program, it stores the command 
line that invoked the job in this area. 

(When TRSDOS-16 stores a command line it 
terminates it with a carriage-return character. 
However, when MOVBUF retrieves a command line 
80 characters long, it does not retrieve the 
carriage return, implied 81st character.) 

There are two ways to alter this buffer: 

1. A MOVBUF request from memory to buffer overwrites 
anything in the buffer. Note that 80 bytes (50 Hex 
bytes) are always moved. 

2. A DOSCMD request does an implied move into the 
buffer before executing the request. Anything 
previously stored in the buffer is lost. 


Entry Conditions 
Byte-offset 0-1 
6-9 
10-11 


267 

user buffer address 

switch 

0 = Retrieve 
non-zero = Store 


Exit Conditions 

Byte-offset 2-3 error code 


Radio /hack 


175 











TRSDOS 16 OWNER'S MANUAL 


TRS-80 


TECHNICAL INFORMATION 


Example 

• 


MOVBUF 

• 

LDA 

. A0, SVC BLOCK 


MOVW 

@A0,#MOVBUF SVC NUMBER 


LDA 

.Al,BUFFER 


STL 

. Al, 6@A0 


MOVW 

10@A0,#FETCH SWITCH 


BRK 

#0 


TESTW 

2@A0 


BNE 

• 

ERROR 

SVC BLOCK 

o 



RDATAB 

32,0 

MOVBUF SVC NUMBER 


BUFFER 

EQUW 

267 


RDATAB 

80,0 

FETCH SWITCH 



EQUW 

0 
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OPEN Function Code 40 

Open File 


Creates new files and opens existing files. 

Once a given file has been opened, OPEN assigns a unique 
file identification number to the file. This number is 
used in all other file processing SVC's to designate that 
specific file. 

Entry Conditions 


Byte-offset 

0-1 

40 


6-9 

filespec address 


10-13 

parameter list address 

Exit Conditions 


Byte-offset 

2-3 

error code 

14-15 

file identification number 


The filespec address is the 32-bit address of a valid 
TRSDOS-16 filespec terminated by a carriage return. 

The parameter list address is the address of a 5-bytes 
field (0-4) which contains: 

Byte Contents 


00 access code 



"R" 

Read access 

to the file 


"W" 

Read/Write 

(data files) 


up n 

Read/Write 

access to Z80 program 



files 


01 

record length in 

bytes 

02 

file 

type 



II pit 

fixed 



"V" 

variable 


03 

creation code (0 

-3 — see table) 


04 user attribute byte 
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The creation code specifies the way TRSDOS-16 opens the 
file: 

Code Function 


0 Open the file only if it already exists. Do 
not create a new file. The record length and 
end of file pointers are not reset. Exclusive 
access only. 


1 Creates a new file. Does not open an existing 
file (returns an error if a file of the 
same name already exists on the specified 
drive). Resets the record length and end of 
file. Exclusive access only. 


2 Open a new file. If a file of the same name 
already exists, overwrite it. Resets record 
length and end of file. Exclusive access 
only. 


3 Opens an existing file for shared access. The 
file MUST already exist (same as mode 0). 


The user attribute byte allows you to give your own 
identification number to certain types of data files. 

You can use 0 or any number from 32 - 255 for this value. 

TRSDOS-16 will not examine this user attribute; it is 
solely for your convenience. 

You can assign this user attribute only to files you open 
with a creation code of 1 or 2. Files opened with a 
creation code of J0 or 3 will retain the file's previously 
assigned user attribute . All files created with the 
CREATE command will have a user attribute value of zero. 

The file identification number is a unique number 
assigned to each file when it is opened. 
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Example 


OPEN LDA 

.A0,SVC BLOCK 

MOVW 

@AJ0, #OPEN SVC NUMBER 

LDA 

.Al,FILE NAME 

STL 

. Al, 6 @ AJ0 

LDA 

.Al,PARAM LIST 

MOVW 

@Al,#WRITE ACCESS 

MOVW 

1@Al,#RECORD LENGTH 

MOVW 

2@Al,#FIXED FILE 

MOVW 

3@Al,#OPEN ONLY IF EXISTS 

MOVW 

4@al,#USER ATTRIB 

STL 

. Al, 10@AJ0 

BRK 

#J0 

TESTW 

20AJ0 

BNE 

• 

ERROR 

• 

SVC BLOCK 

RDATAB 

32,0 

OPEN SVC NUMBER 

EQUW 

40 

FILE NAME 

TEXT 

'TEST/SRC' 

DATAB 

H' 0D 

PARAM LIST 

RDATAB 

5,0 

WRITE ACCESS 

EQUB 

•P 

RECORD LENTGH 

EQUB 

80 

FIXED FILE 

EQUB 

• F 

OPEN ONLY IF EXISTS 

EQUB 

0 

USER ATTRIB 

EQUB 

66 
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OPENDO Function Code 140 

Open DO File 


Creates a special file or opens an existing one. 

OPENDO opens a special file that will not be closed by 
returning to TRSDOS-16 Ready or executing the CLOSEF SVC. 

OPENDO is useful for chaining programs. 

Once a given file has been opened, OPENDO assigns a unique 
file identification number to the file. This number is 
used in all other file processing SVC's to designate that 
specific file. 

Only one file may be opened with OPENDO at a time. 
Therefore, this call cannot be made if a DO file is active. 


Entry Conditions 
Byte-offset 0-1 
6-9 
10-13 


140 

filespec address 
parameter list address 


Exit Conditions 

Byte-offset 2-3 error code 

14-15 file identification number 


The filespec address is the 32-bit address of a valid 
TRSDOS-16 filespec terminated by a carriage return. 


The parameter list address is the address of a 5-bytes 
field (0-4) which contains: 

Byte Contents 


00 access code 

"R" Read access to the file 
"W" Read/Write (data files) 

"P" Read/Write access to Z80 program 
files 


You may not execute the SPOOL command and a DO file at the 
same time. The first one executed will be given priority 
over the second. 
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Byte 


Contents 


01 record length in bytes 

02 file type 

"F" fixed 
"V" variable 

03 creation code (0-3 — see table) 

04 user attribute byte 


The creation code specifies the way TRSDOS-16 opens the 
file: 


Code 


Function 


0 Open the file only if it already exists. Do 
not create a new file. The record length and 
end of file pointers are not reset. Exclusive 
access only. 


1 Creates a new file. Does not open an existing 
file (returns an error if a file of the 
same name already exists on the specified 
drive). Resets the record length and end of 
file. Exclusive access only. 


2 Open a new file. If a file of the same name 
already exists, overwrite it. Resets record 
length and end of file. Exclusive access 
only. 


3 Opens an existing file for shared access. The 
file MUST already exist (same as mode 0). 


The user attribute byte allows you to give your own 
identification number to certain types of data files. 

You can use 0 or any number from 32 - 255 for this value. 

TRSDOS-16 will not examine this user attribute ; it is 
solely for your convenience. 


You can assign this user attribute only to files you open 
with a creation code of 1 or 2. Files opened with a 
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creation code of 0 or 3 will retain the file's previously 
assigned user attribute . All files created with the 
CREATE command will have a user attribute value of zero. 

The file identification number is a unique number assigned 
to each file when it is opened. 


Example 


OPENDO 


LDA 

. A0, SVC BLOCK 

MOVW 

@A0, #OPENDO SVC NUMBER 

LDA 

.Al f FILE NAME 

STL 

. Al, 6 @A0 

LDA 

.Al,PARAM LIST 

MOVW 

@Al,#WRITE ACCESS 

MOVW 

1@Al,#RECORD LENGTH 

MOVW 

2@Al,#FIXED FILE 

MOVW 

3@Al,#OPEN ONLY IF EXISTS 

MOVW 

4@al,#USER ATTRIB 

STL 

. Al, 10@AJ0 

BRK 

#0 

TESTW 

2@A0 

BNE 

ERROR 


RDATAB 

OPENDO SVC NUMBER 

32,0 

EQUW 

FILE NAME 

140 

TEXT 

'TES' 
H' 0D 

DATAB 

PARAM LIST 

RDATAB 
WRITE ACCESS 

5,0 

EQUB 

RECORD LENTGH 

'P 

EQUB 

FIXED FILE 

80 

EQUB 

OPEN ONLY IF EXISTS 

• F 

EQUB 

USER ATTRIB 

0 

EQUB 

66 
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PRCHAR 

Print Character 


Function Code 18 


Sends one character to the Printer's buffer. 

Note: Most printers don't print until their buffer is 

filled or until they receive a carriage return. (See your 
printer's manual for information.) 

Normally, TRSDOS-16 intercepts certain codes and does not 
send them directly to the printer. There are several ways 
to override some or all of these character translations. 
See PRINIT and PRCTRL SVCs. 

While the serial printer option is selected, allowing 
printer output to Channel B, two INPUT characters are 
recognized from Channel B. These will affect all serial 
printer output operations: 


ASCII 

Hex 



Name 

Code 

Result 


DC 3, "CTRL-S" 

13 

Pause 

Printing 

DC1, "CTRL-Q" 

11 

Resume 

Printing 


INTERCEPTED CODES 


ASCII 

NAME 

HEX 

CODE 

RESULT TO PRINTER 

Tab 

09 

From one to eight spaces are sent 
to provide a tab function. 

Vertical 

Tab 

0B 

Same as form feed below. 

Form 

Feed 

0C 

TRSDOS-16 sends enough carriage 
returns or line feeds to the 
printer to advance the paper to the 
next top of form. 
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ASCII 

NAME 

HEX 

CODE 

RESULT TO PRINTER 

Carriage 

Return 

0D 

When the current line is empty, (no 
characters printed since the last 
carriage return or line feed), 
TRSDOS-16 translates this as a 
line feed to allow correct 
operation of Radio Shack printers. 

In the auto line feed mode, H'0A' 
is sent after every H'^D'. 

Special 

8D 

TRSDOS-16 sends a carriage return 
to the printer. In the auto line 
feed mode, using this code allows 
you to send a carriage return 
without a line feed. 


Entry Conditions 
Byte-offset 0-1 
6-7 


18 

character to output 


Exit Conditions 

Byte-offset 2-3 error code 


Example 


Before executing this program, load register Al with the 
character from byte-offset 8 of the KBCHAR SVC routine. 


PRCHAR 

LDW 

.Al,8@A0 


LDA 

.A0,SVC BLOCK 


MOVW 

0A0,#PRCHAR SVC NUMBER 


STW 

.Al,6@A0 


BRK 

#0 


TESTW 

2@A0 


BNE 

• 

ERROR 

SVC BLOCK 

• 



RDATAB 

32,0 

PRCHAR SVC NUMBER 



EQUW 

18 
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PRCTRL Function Code 95 

Control Printer Operation 


Provides you with various printer options and lets you check 
the status of printer-related functions. 

If you are using the spooler's capture function, the 
captured data is sent directly to the capture-file — 
regardless of what control settings are selected. If you 
are using the spooler's background printing function, the 
printed data is interpreted according to the currently 
selected control settings. See SPOOL for details. 


You can operate with two printers, by switching between the 
serial and parallel output modes. One printer can use the 
automatic control features of TRSDOS (auto form feed, etc.), 
while the other printer is controlled by the program. This 
is necessary since only one set of control counters is 
maintained. 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-9 


95 

option code (See Table 2) 

option value (applicable only with 

option codes 3 and 4) 


Exit Conditions 
Byte-offset 2-3 

10-11 

12-13 

14-15 

16-17 

18-19 


error code 

physical page length 

logical page length 

logical line length 

number of characters printed on 

present line 

number of lines on present page 


The option code is a 16-bit value used to select the print 
control option you wish. 

The option value is used by option codes 3 and 4 which 
allow you to reset the current line count or the current 
character count. Put the new values in this byte-offset. 


Radio /hack 


185 



















TRSDOS 16 OWNER'S MANUAL 


TECHNICAL INFORMATION 


TRS-80 


Available option codes are: 
CODE OPTION 


0 Get printer status only (see Exit Conditions) 

1 Select serial printer driver (you must initialize 
channel B first) 

2 Select parallel printer driver 

3 Reset current line count to the value contained in 
option value * 

4 Reset current character count on current line to value 
contained in option value * 

5 Begin transparent mode * 

6 End transparent mode * 

7 Begin dummy mode * 

8 End dummy mode * 

9 Begin auto line-feed after carriage return * 

10 End auto line-feed after carriage return * 


* EXPLANATION OF OPTIONS 


EXPLANATION OF OPTIONS 
Serial/Parallel Printer Option 

While the serial printer option is selected, allowing 
printer output to Channel B, two INPUT characters are 
recognized from Channel B. These will affect all serial 
printer output operations: 


ASCII 

Hex 


Name 

Code 

Result 

DC3, "CTRL-S" 

13 

Pause Printing 

DC1, "CTRL-Q" 

11 

Resume Printing 


Line count/Character count 

TRSDOS-16 maintains a single line counter and a single 
character counter. 
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Transparent Mode 

The transparent mode overrides all data translation. All 
data bytes go directly to the printer; TRSDOS-16 does not 
examine the contents or update the line and character 
counts. 

Normally, TRSDOS-16 "intercepts" certain control characters 
and interprets them. In this way, TRSDOS-16 provides 
printer-related features which may not be available from the 
printer. 

For example, tabs (H'09') are intercepted so that TRSDOS-16 
can send the appropriate number of spaces to provide the tab 
function. Form feeds (H'0C' or H'0B') are intercepted so 
that TRSDOS-16 may advance the paper to the top of the next 
form. 

Special settings of the printer initialization values can 
override individual code translation. See SVC PRINIT for 
details. 


Dummy Output Mode 

The dummy mode "throws away" all printer output and returns 
with a "good" (Z flag set) return code. During dummy mode 
operation, the line count and character count remain 
unchanged. 


Auto Line Feed 

Normally, the TRSDOS-16 printer driver doesn't output line 
feeds after carriage returns because most Radio Shack 
printers do an automatic line-feed after every carriage 
return. 

If your printer does not perform automatic line-feeds after 
carriage returns, you may enable the TRSDOS-16 auto 
line-feed function. 

While the function is enabled, TRSDOS-16 outputs a line-feed 
after each carriage return. This is true in all modes, 
including the transparent mode. 

Note: In the auto line-feed mode, you can send a carriage 
return with no line-feed by outputting the code H'8D'. If 
the printer can overprint, this code returns the carriage 
without advancing the paper. 
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PRECEDENCE OF OPTIONS 

The priority of the available options are (in descending 
order): 

Dummy Mode 

Auto Line-Feed after Carriage Return 
Transparent Mode 
Normal Mode 


Example 


PRCTRL LDA 


MOVW 

MOVW 

BRK 


. Aj3, SVC BLOCK 

@AJ0 , #PRCTRL SVC NUMBER 

6@AJEJ, #GET STATUS OPTION 


TESTW 

BNE 


20AJ0 

ERROR 


SVC BLOCK 

RDATAB 32,0 
PRCTRL SVC NUMBER 

EQUW 95 

GET STATUS OPTION 

EQUW 0 
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PRINIT Function Code 17 

Printer Initialization 


Initializes the printer driver. 

It does not advance the printer paper and does not check 
printer status or availability. It will operate even if the 
printer is offline. 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-9 
10-11 


17 

physical page length 

logical page length 

logical line length 


Exit Conditions 

Byte-offset 2-3 error code 


physical page length is the number of lines that can be 
printed on one page. It is normally 66. 

logical page length is the number of lines you want printed 
on each page. It must be less than physical page length . 
After that number of lines has been printed, ( logical page 
length < physical page length ) TRSDOS-16 will send a 
top-of-page request to the printer (form feed). 

logical line length is the maximum number of characters to 
be printed on each line. Once that number has been reached, 
the line will be printed and a new line is begun 
(wrap-around). 


Notes: 

1. If logical page length and physical page length are 

equal and non-zero, TRSDOS-16 will not do an end-of-page 
skip. It will translate form feed into the correct number 
of line feeds necessary to get to the top of the next 
page. 
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2. If either logical page length or physical page length 
are zero, the other must also be zero. When both are 
equal to zero, form feeds (H'0C) and vertical tabs (H'0B) 
are not translated into line feeds, but are sent directly 
to the printer. 

3. If logical line length is zero, then tab characters 
(H'09) will not be translated into spaces, but sent 
directly to the printer. TRSDOS-16 will still maintain 
an internal character count, with tabs counting as one 
character. 

4. On Exit, current character count and line-in-page count 
are reset to zero. 

5. TRSDOS-16 assumes the printer is at top-of-page when 
this SVC is executed. 


6. DUMMY and TRANSPARENT modes are reset to NORMAL. 

AUTO-LINEFEED and DUAL options are unaffected by this 
SVC. (See PRCTRL) 


7. When the system is powered-up or reset, the following 
defaults are assumed: 


physical page length 
logical page length 
logical line length 

The other options selected 

Auto-Line Feed 
Dummy Mode 
Transparent Mode 


= 66 

= 60 

= 132 

during initialization are: 

= off 

= off 

= off 


Example 

PRINIT LDA 
MOVW 
MOVW 
MOVW 

MOVW 


. A0 ,SVC BLOCK 
@A0, #PRINIT SVC NUMBER 
6@A0,#PHY PAGE LENGTH 
8@AJ0,#LOG PAGE LENGTH 
10§A0,#LOG LINE LENGTH 
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BRK 

#J0 



TESTW 

2@AJ0 



BNE 

ERROR 

SVC 

• 

• 

BLOCK 




RDATAB 

32,0 

PRINIT SVC NUMBER 




EQUW 

17 

PHY 

PAGE 

LENGTH 




EQUW 

32 

LOG 

PAGE 

LENGTH 




EQUW 

30 

LOG 

LINE 

LENGTH 




EQUW 

45 
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PRLINE Function Code 19 

Print Line 


Sends a line of characters to the printer's buffer. The 
line can include control characters as well as printable 
data. 

See PRCHAR for a listing of intercepted codes. 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-9 


10-13 


19 

length of line (0-255) 
terminator character to send after 

last character in buffer 

address of buffer 


Exit Conditions 

Byte-offset 2-3 error code 


Example 

In this example, TRSDOS-16 retrieves the length of line, 
terminator character, and address of buffer from the KBLINE 
SVC routine. 


PRLINE 


LDW 

.Al,12@A0 *Get 

length of line 

LDW 

.A2,14@A0 *Get 

terminator character 

LDA 

•A3,KEYBD BUFFER *Get buffer address 

LDA 

.A0,SVC BLOCK 


MOVW 

@A0,#PRLINE SVC 

NUMBER 

STW 

.Al,6@A0 


STW 

.A2,8@A0 


STL 

.A3,10@A0 


BRK 

#0 


TESTW 

2@A0 


BNE 

ERROR 
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SVC BLOCK 

RDATAB 32,0 

PRLINE SVC NUMBER 

EQUW 19 
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REAONX 

Read Next Record 


Function Code 34 


Reads the next record after the current record (the last 
record accessed). If you have just opened the file, READNX 
reads the first record. 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-11 
12-13 


34 

file identification number 

record buffer address 

record lock flag 


Exit Conditions 

Byte-offset 2-3 error code 


The file identification number is a unique number assigned 
to each file when it is opened. 

The record buffer address is a 32-bit address that points 
to the beginning of a 256-byte Record Buffer; that is where 
the record will be placed after the disk read. 

If the record lock flag is non-zero, the specified record 
remains locked until the user program performs an UNLOCK on 
the record. 

If the record lock flag is zero, the record is not locked. 


Example 

Prior to this routine, store the file identification number 
in register Al. 


READNX LDA 
MOVW 
STW 
LDA 
STL 


. AJ0, SVC BLOCK 

@AJ0,#READNX SVC NUMBER 

.Al, 6@AJ0 

.A2,RECORD BUFFER AREA 
. A2,8@AJ0 
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BRK 

#J3 


TESTW 

2@AJ0 


BNE 

• 

ERROR 

• 

SVC BLOCK 



RDATAB 

32 ,0 

READNX 

SVC NUMBER 



EQUW 

34 

RECORD 

BUFFER AREA 



RDATAB 

256 ,0 
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RENAME Function Code 47 

Rename File 


Changes the name and/or extension of a file. 

This SVC cannot change the password. If the old filespec is 
password protected, you must specify the password and the 
new filespec retains the same password. 

The new filespec can't refer to an existing file. 


Entry Conditions 
Byte-offset 0-1 
6-9 
10-13 


47 

old filespec address 

new filespec address > 


Exit Conditions 

Byte-offset 2-3 error code 


The filespec address is the 32-bit address of a valid 
TRSDOS-16 filespec terminated by a carriage return. 


Example 


RENAME 


SVC BLOCK 

RENAME SVC NUMBER 
EQUW 


LDA 

.A0,SVC BLOCK 

MOVW 

@A0,#RENAME SVC NUMBER 

LDA 

.Al,OLD NAME 

STL 

.Al,6@A0 

LDA 

.Al,NEW NAME 

STL 

.Al,10@A0 

BRK 

#0 

TESTW 

2@A0 

BNE 

• 

ERROR 

• 

RDATAB 

32,0 


47 


Radio/hack® 


196 











TRSDOS 16 OWNER'S MANUAL 


TECHNICAL INFORMATION 
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NAME 

TEXT 

'TEST/SRC' 

DATAB 

H ' 0D 

NAME 

TEXT 

'PROGRAM/SRC' 

DATAB 

H'jZfD 
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RESET Function Code 129 

Reset Memory 


It is the same as pressing the RESET switch. 
Reset will not close an OPENDO file. 


Entry Conditions 
Byte-offset 0-1 256 

6-7 00 (Reserved) 


Exit Conditions 

Byte-offset 2-3 error code 


Example 


• 

RESET LDA 

MOVW 
MOVW 
BRK 


. AJ0 , SVC BLOCK 

@AJ0, #RESET SVC NUMBER 

6@Ajef,#00 

#J3 


SVC BLOCK 

RDATAB 32 ,J0 

RESET SVC NUMBER 

EQUW 129 
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RS232C Function Code 55 

Initialize RS-232-C Channel 


Sets up or disables either channel A or B. 

This routine sets the standard RS-232C parameters, and 
defines a pair of supervisor calls for I/O to the specified 
channel. When you initialize Channel A, SVC's 96, 97, 100 
are defined; when you initialize Channel B, SVC's 98, 99, 
and 101 are defined. See ARCV, ATX, BRCV, BTX, ACTL and 
BCTL. 


Entry Conditions 
Byte-offset 


Byte-offset 


0-1 

55 

6-7 

option value 


0 = deactivate 


non-zero = activate 

8-11 

parameter list address 

iS 

2-3 

error code 


Set the option value to 0 to deactivate the serial 
channel. Any non-zero value activates the channel. You 
must always deactivate the channel (turn it off) before you 
set the parameters. 

The parameter list address is the address of a 6-byte 
field (0-5) which contains: 

Byte Contents 


00 Channel code 'A' or 'B' (ASCII) 

01 Baud Rate: 

1 = 100 baud 

2 = 150 baud 

3 = 300 baud 

4 = 600 baud 

5 = 1200 baud 

6 = 2400 baud 

7 = 4800 baud 

8 = 9600 baud 
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Byte 


-TRS-BO 

Contents 


Some applications do not run well at the 
higher baud rates. 

02 Data Word Length (5-8 bits) 

03 Parity 'E' (even), 'O' (odd), or 'N' (none) 

04 Number of stop bits (1 or 2) 

05 End of list marker (binary 0) 


Example 


RS232C LDA 

. A0, SVC BLOCK 

MOVW 

@A0,#RS232C SVC NUMBER 

LDA 

.Al,PARAM LIST 

MOVW 

@A1,#CHANNEL A 

MOVW 

l@Al,#BAUD RATE 

MOVW 

2@Al,#DATA WORD LENGTH 

MOVW 

3@Al,#EVEN PARITY 

MOVW 

4@A1,#STOP BITS 

MOVW 

5@Al,#END LIST 

STL 

. Al, 8@A0 

BRK 

#0 

TESTW 

2@A0 

BNE 

• 

ERROR 

• 

SVC BLOCK 


RDATAB 

32,0 

RS232C SVC NUMBER 


EQUW 

55 

PARAM LIST 


RDATAB 

6,0 

CHANNEL A 


EQUB 

'A 

BAUD RATE 


EQUB 

3 

DATA WORD LENGTH 


EQUB 

7 

EVEN PARITY 


EQUB 

'E 
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STOP BITS 
END LIST 


® 


EQUB 1 

EQUB 00 
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SETBRK Function Code 269 

Set <BREAK> 


Lets you enable the <BREAK> key by defining a <BREAK>-key 
processing program. 

Whenever the <BREAK> key is pressed, your processing program 
takes over. On entry to the <BREAK> processing program, the 
return address of the interrupted routine is on the User 
Stack and can be returned to with an RTR instruction (return 
with restore). 

See 'PROGRAMMING WITH USER INTERRUPTS' for further 
information. 


Entry Conditions 
Byte-offset 0-1 
6-7 


8-11 


269 

switch 

0 = Off (normal TRSDOS-16 break 
processing) 

1 = On (user programmed break 

processing) 

2 = Disable (TRSDOS-16 ignores 

<BREAK> key completely) 
transfer address 

0 = Fetch 
non-zero = Store 


Exit Conditions 

Byte-offset 2-3 error code 


The transfer address is the address you want to jump to 
when the <BREAK> key is pressed. It must be even. 

Example 


SETBRK 

LD0 

.A0,SVC BLOCK 


MOVW 

@A0,#SETBRK SVC NUMBER 


MOVW 

6@A0,#SWITCH ON 


MOVL 

8@A0,#TRANSFER ADDRESS 
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BRK #0 

TESTW 2@A0 

BNE ERROR 


SVC BLOCK 

RDATAB 32,0 

SETBRK SVC NUMBER 

EQUW 269 

SWITCH ON 

EQUW 1 

TRANSFER ADDRESS 

EQUL H'8000 
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SETTRP Function Code 266 

Sets a Trap Vector 


Allows you to set or remove a trap vector. When a BRK is 
executed (either through the BRK-BRKV instructions or an 
error trap) control goes to the address specified by the 
user. See SETBRK and PROGRAMMING WITH USER INTERRUPTS for 
further information on interrupts. 


Entry Conditions 


Byte-offset 

0-1 

266 


6-7 

function code 


8-9 

vector number 


10-13 

vector address 

Exit Conditions 


Byte-offset 

2-3 

error code 


14-17 

previous vector address 


The function codes are: 

0 - Install (SET) trap 

1 - Remove trap 

2 - Remove all traps (except BRK 0 ) 


The available vector numbers are: 

Vector # Assignment 


1-15 

Trap vectors 1-15 

16 

Illegal Instruction 

17 

Zero Divide 

18 

CHK Instruction 

19 

TRAPV Instruction 

20 

Privilege Violation 

21 

Line 1010 Emulator 

22 

Line 1111 Emulator 

23 

Access out of Partition 

24 

Odd Address Error 


Note that BRK 0 is reserved for implementation of supervisor 
calls. 
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The Emulators (Vectors 21 and 22) are illegal opcodes which 
can be trapped. These are opcodes that have an 'A' or 'F' 
in the first nybble (high order 4 bits). That is Axxx or 
Fxxx as an opcode. 

The vector address is the address to jump to when the trap 
is executed, it must be even. 


Example 


SETTRP 

LDA 

.A0,SVC BLOCK 



MOVW 

@A0,#SETTRP SVC NUMBER 


MOVW 

6@A0,#SET TRAP 

FUNCTION 


MOVW 

8@A0,#TRAP 16 



MOVL 

10@A0,#TRAP 16 

ADDRESS 


BRK 

#0 



TESTW 

2@A0 



BNE 

• 

ERROR 


• 

SVC BLOCK 




RDATAB 

32,0 


SETTRP 

SVC NUMBER 




EQUW 

266 


SET TRAP FUNCTION 




EQUW 

0 


TRAP 16 

EQUW 

16 


TRAP 16 

ADDRESS 




EQUL 

H'5000 
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UNLOCK Function Code 136 

Unlock Record 


Unlocks a specified record number, or all records within a 
specified file, that you previously locked. 

See READNX or DIRRD for information on how to lock a record. 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-9 


136 

file identification number 

record number 


Exit Conditions 

Byte-offset 2-3 error code 


The record number contains the logical record number of 
the file to be UNLOCKed. Specifying a -1 in the record 
number byte-offset UNLOCKS all the records in the file 
which are locked by the calling user. 

The file identification number is a unique number assigned 
to each file when it is opened. 


Example 

Before executing this program, store the file identification 


number 

in register 

Al. 

UNLOCK 

• 

• 

LDA 

.A0,SVC BLOCK 


MOVW 

@A0,#UNLOCK SVC NUMBER 


STW 

.Al,6@A0 


MOVW 

8@A0,#UNLOCK ALL RECORDS 


BRK 

#0 


TESTW 

2@A0 


BNE 

ERROR 
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SVC BLOCK 


RDATAB 

32,0 

UNLOCK SVC NUMBER 

EQUW 

136 

UNLOCK ALL RECORDS 


EQUW 

-1 
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VDCHAR 

Video Character 


Function Code 8 


Outputs a character to the display at the current cursor 
position. 

TRSDOS-16 ignores the control codes not listed in the 
following chart. 


KEY 

HEX 

CODE 

FUNCTION 

FI 

01 

Blinking cursor on. 

F2 

02 

Cursor off. 

CTRL D 

04 

Turns on steady cursor. 

BACKSPACE 

08 

Moves cursor back one position and blanks 
the character at that position. 

TAB 

09 

Advances cursor to next tab position. Tab 
positions are at 8-character boundaries, 

8, 16, 24, 32, ... . 

CTRL J 

0A 

Line feed—cursor moves down to next row, 
same column position. 

CTRL K 

0B 

Positions cursor to beginning of previous 
line. 

ENTER 

0D 

Moves cursor down to beginning of next line. 

CTRL N 

0E 

Turns dual routing on. 

CTRL 0 

0F 

Turns dual routing off. 

CTRL T 

14 

Homes cursor (upper left corner) 

CTRL W 

17 

Erases to end of line, cursor doesn't move 

CTRL X 

18 

Erases to end of screen, cursor doesn't 
move. 

CTRL Y 

19 

Sets Normal Display mode (white on black). 
Remains Normal until reset by programmer. 

CTRL Z 

1A 

Sets Reverse Display mode (black on white). 
Remains Reverse until reset by programmer. 

ESC 

IB 

Erases screen and homes cursor (position 0). 

left arrow 

1C 

Moves cursor back one position. 

right arrow 

ID 

Moves cursor forward one position. 

up arrow 

IE 

Sets 80 character line and clears Display. 

down arrow 

IF 

Sets 40 character line and clears Display. 
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Entry Conditions 
Byte-offset 0-1 8 

6-7 character to output (0-127) 


Exit Conditions 

Byte-offset 2-3 error code 


Example 

This routine clears the screen. 


• 

VDCHAR LDA 
MOVW 
MOVW 
BRK 
TESTW 
BNE 


.A0,SVC BLOCK 
@A0, #VDCHAR SVC NUMBER 
6@A0, #CLS 
#0 

2@A0 

ERROR 


SVC BLOCK 

RDATAB 

VDCHAR SVC NUMBER 
EQUW 

CLS 

EQUW 


32,0 

8 

H'lE 
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VDINIT Function Code 7 

Video Initialization 


You might want to call this routine before starting any I/O to 
the Video Display. It blanks the screen and homes the cursor 
(moves the cursor to the upper left corner of the video 
display). 


Entry Conditions 
Byte-offset 0-1 
6-7 


8-9 


7 

character size switch 

0 = 40 characters/line 
non-zero = 80 characters/line 
normal/reverse switch 
0 = reverse mode (black on green/ 
black on white) 

non-zero = normal mode (green on 
black/white on black) 


Exit Conditions 

Byte-offset 2-3 error code 


Example 


VDINIT 


SVC BLOCK 


LDA 

. A0, SVC BLOCK 

MOVW 

@A0, #VDINIT SVC NUMBER 

MOVW 

6@A0,#CHAR80 

MOVW 

8@A0, #NORMAL 

BRK 

#0 

TESTW 

2@A0 

BNE 

• 

ERROR 

• 

RDATAB 

32,0 


VCINIT SVC NUMBER 

EQUW 7 
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CHAR80 

NORMAL 


EQUW 

EQUW 


1 

1 
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VDLINE Function Code 9 

Video Line 


Writes a specified text buffer to the display, starting at the 
current cursor position. The text buffer must contain codes less 
than H'80. 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-9 

10-13 


9 

buffer size (0 - 255) 
terminator character to be sent 

after the buffer text 

buffer address 


Exit Conditions 
Byte-offset 2-3 

14-15 

16-17 


error code 

on error (number of characters not 
sent) 

on error (character causing error) 


The buffer pointed to by the buffer address should contain 
ASCII codes in the range 0 to 127. 

This routine handles control codes in the buffer in the same 
manner as in the VDCHAR routine. 


Example 

This example retrieves the buffer size, terminator 
character, and buffer Address from the KBLINE SVC routine. 


LDW 

LDW 

LDA 

VDLINE LDA 
MOVW 
STW 
STW 
STL 


.Al,12@A0 *Get length of input line 

,A2,14@A0 *Get terminator character 

.A3,KEYBD BUFFER *Get address of buffer 

.A0,SVC BLOCK 

@A0,#VDLINE SVC NUMBER 

.Al,6@A0 

.A2,8@A0 

•A3,10@A0 
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BRK #J0 

TESTW 2@AJ0 

BNE ERROR 


SVC BLOCK 

RDATAB 32,0 

VDLINE SVC NUMBER 

EQUW 9 
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VERSION 


Get Version of Operating System 


Function Code 137 


Determines the version of software currently servicing 68000 
requests. 


Entry Conditions 
Byte-offset 0-1 

137 



Exit Conditions 

Byte-offset 2-3 

error 

code 


6-7 

major 

version 

level 

8-9 

minor 

version 

level 

10-11 

patch 

level 



The major version level is the integral portion of the 
version number printed during startup. 


The minor version level is the fractional portion of this 
quantity. 


The patch level is any level following the version number. 

For example, version 2.0a returns major version level 2, 
minor version level 0, and patch level 'a'. 


Example 


• 

• 

VERSION LDA 

. A0 ,SVC BLOCK 

MOVW 

@A0,# VERSION SVC NUMBER 

BRK 

#0 

TESTW 

2@A0 

BNE 

• 

ERROR 

• 

SVC BLOCK 

RDATAB 

32,0 

VERSION SVC NUMBER 

EQUW 

137 
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VIDKEY Function Code 12 

Video Key 


This routine combines the functions of VDLINE and KBLINE. 

It writes a buffer of data to the display, starting at the 
current cursor position, then waits for a line from the 
keyboard. 

Once the text message has been displayed, the cursor will be 
positioned immediately after the last character displayed. 

To move it to another position, a control code can be placed 
at the end of the text buffer. 

VIDKEY then uses KBLINE to get a line from the keyboard. 

Note that before starting the line input, all previously 
stored keystrokes are cleared. 

Refer to KBCHAR and VDCHAR for a list of control codes and 
other details. 


Entry Conditions 
Byte-offset 0-1 
6-7 


8-9 


10-13 

14-17 


Exit Conditions 
Byte-offset 2-3 

18-19 


20-21 


12 

number of characters to be 

displayed (0-255) 

length of keyboard input field 

(0-255) 

address of keyboard input buffer 

address of display text buffer 


error code 

on error (number of characters not 
sent) 

on error (character causing error) 
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Example 


VIDKEY LDA 

. A0, SVC BLOCK 

MOVW 

@A0, #VIDKEY SVC NUMBER 

MOVW 

6@A0,#DISPLAY COUNT 

MOVW 

8@A0, # INPUT COUNT 

LDA 

.Al,KEYBD BUFFER 

STL 

.Al,10@A0 

LDA 

.Al,MESSAGE PROMPT 

STL 

.Al,14@A0 

BRK 

#0 

TESTW 

2@A0 

BNE 

• 

ERROR 

• 

SVC BLOCK 

RDATAB 

32,0 

VIDKEY NUMBER 

EQUW 

12 

DISPLAY COUNT 

EQUW 

21 

MESSAGE PROMPT 

TEXT 

'ENTER THE ANSWER HERE 

INPUT COUNT 

EQUW 

20 

KEYBD BUFFER 

RDATAB 

20,0 
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WRITNX Function Code 43 

Write Next Record 


Writes the next record after the last record accessed; i.e., 
this routine writes records sequentially. 

If WRITNX is the first access after opening the file, it 
writes the first record. 


Entry Conditions 
Byte-offset 0-1 
6-7 
8-11 


43 

file identification number 

record buffer address 


Exit Conditions 

Byte-offset 2-3 error code 

The file identification number is a unique number assigned 
to each file when it is opened. 

The record buffer address is a 32-bit address that points 
to the beginning of a 256-byte Record Buffer; that is where 
the record will be placed after the disk read. 


Example 

Store the File Identification Number in register Al before 
executing this routine. 


WRITNX 


LDA 

. A0, SVC BLOCK 

MOVW 

@A0,#WRITNX SVC NUMBER 

STW 

. Al, 6@A0 

LDA 

,A2,RECORD BUFFER AREA 

STL 

. A2,8@A0 

BRK 

#0 

TESTW 

2@A0 

BNE 

ERROR 
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SVC BLOCK 



RDATAB 

32,0 

WRITNX 

SVC NUMBER 



EQUW 

43 

RECORD 

BUFFER AREA 



RDATAB 

256,0 
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